org.globalplatform
Interface SecureChannel

All Superinterfaces:

javacard.framework.Shareable

All Known Subinterfaces:

SecureChannelx, SecureChannelx2

public interface SecureChannel
extends javacard.framework.Shareable

This defines an interface to be used by an Application that may want to delegate the handling of entity authentication and APDU security to its associated Security Domain. This interface is designed to offer interoperability to the Application in that it requires no knowledge of the mechanisms used to perform the authentication or of the scheme used for APDU security and shall allow an Application to interface correctly with a Security Domain immaterial of the mechanisms or schemes used. Prior to using this interface, an Application is required to obtain a handle to its associated Security Domain’s SecureChannel interface object by invoking the GPSystem.getSecureChannel() method. The SecureChannel interface shall only be exposed through the GPSystem.getSecureChannel() method. In all cases where the Application passes the APDU buffer as a parameter to the Security Domain, the class byte of the APDU shall not be modified. This ensures that the Security Domain knows the logical channel number. If the card supports logical channels, it is the responsibility of the Security Domain to correctly manage the logical channel information when processing the APDU.

Since:

export file version 1.0

Field Summary

static byte	ANY_AUTHENTICATED Entity Any Authentication has occurred (0x40).
static byte	AUTHENTICATED Entity Authentication has occurred as Application Provider (0x80).
static byte	C_DECRYPTION The unwrap method will decrypt incoming command data (0x02).
static byte	C_MAC The unwrap method will verify the MAC on an incoming command (0x01).
static byte	NO_SECURITY_LEVEL Entity Authentication has not occurred (0x00).
static byte	R_ENCRYPTION The wrap method will encrypt the outgoing response data (0x20).
static byte	R_MAC The wrap method will generate a MAC for the outgoing response data (0x10).

Method Summary

short	decryptData(byte[] baBuffer, short sOffset, short sLength) This method is used to decrypt data located in the input buffer.
short	encryptData(byte[] baBuffer, short sOffset, short sLength) This method is used to encrypt data located in the input buffer.
byte	getSecurityLevel() This method returns, from the requester's standpoint, the Current Security Level coded as a bit-map according to Table 10 1 indicating whether entity authentication has occurred and what level of security is currently applicable to command and response messages processed by the unwrap() and wrap() methods.
short	processSecurity(javacard.framework.APDU apdu) Processes security related APDU commands.
void	resetSecurity() This method is used to reset all information relating to the current Secure Channel Session.
short	unwrap(byte[] baBuffer, short sOffset, short sLength) This method is used to process and verify the secure messaging of an incoming command according to the security level and Session Security Level of the current Secure Channel Session.
short	wrap(byte[] baBuffer, short sOffset, short sLength) This method applies secure messaging to the current outgoing response according to the Current Security Level and Session Security Level of the Secure Channel Session.

Field Detail

AUTHENTICATED

static final byte AUTHENTICATED

Entity Authentication has occurred as Application Provider (0x80).

Note:

• Entity Authentication and the level of security that will be applied by the wrap and unwrap methods are not necessarily related. A Security Domain, by default, could verify the MAC on any command passed as a parameter in the unwrap method without entity authentication previously having occurred.

  See Also:

  Constant Field Values

C_DECRYPTION

static final byte C_DECRYPTION

The unwrap method will decrypt incoming command data (0x02).

Note:

• Command data decryption could be indicated along with entity authentication and one or more levels of security.

  See Also:

  Constant Field Values

C_MAC

static final byte C_MAC

The unwrap method will verify the MAC on an incoming command (0x01).

Note:

• MAC verification could be indicated along with entity authentication and one or more levels of security, e.g. a value of '03' indicates that while entity authentication has not occurred, the unwrap method will decrypt the command data of incoming commands and verify the MAC on incoming commands.

  See Also:

  Constant Field Values

R_ENCRYPTION

static final byte R_ENCRYPTION

The wrap method will encrypt the outgoing response data (0x20).

Note:

• Response data encryption could be indicated along with entity authentication and one or more levels of security.

  See Also:

  Constant Field Values

R_MAC

static final byte R_MAC

The wrap method will generate a MAC for the outgoing response data (0x10).

Note:

• MAC generation could be indicated along with entity authentication and one or more levels of security, e.g. a value of '91' indicates that entity authentication has occurred, that the unwrap method will verify the MAC on incoming commands and that the wrap method will generate a MAC on outgoing response data.

  See Also:

  Constant Field Values

NO_SECURITY_LEVEL

static final byte NO_SECURITY_LEVEL

Entity Authentication has not occurred (0x00).

Note:

• Entity Authentication and the level of security that will be applied by the wrap and unwrap methods are not necessarily related. A Security Domain, by default, could verify the MAC on any command passed as a parameter in the unwrap method without entity authentication previously having occurred.
• The wrap and unwrap methods will not apply any cryptographic processing to command or response data.

  See Also:

  Constant Field Values

ANY_AUTHENTICATED

static final byte ANY_AUTHENTICATED

Entity Any Authentication has occurred (0x40).

Note:

Authenticated entity is not the Application Provider of the Application. The level of security that will be applied by the wrap and unwrap methods are not necessarily related. A Security Domain, by default, could verify the MAC on any command passed as a parameter in the unwrap method without entity authentication previously having occurred.

See Also:

Constant Field Values

Method Detail

processSecurity

short processSecurity(javacard.framework.APDU apdu)
                      throws javacard.framework.ISOException

Processes security related APDU commands.

This method is used by an applet to process APDU commands that possibly relate to the security mechanism used by the Security Domain. As the intention is to allow an Application to be associated with a Security Domain without having any knowledge of the security mechanisms used by the Security Domain, the applet assumes that APDU commands that it does not recognize are part of the security mechanism and will be recognized by the Security Domain. The applet can either invoke this method prior to determining if it recognizes the command or only invoke this method for commands it does not recognize. The method sets the compulsory Session Security Level that is established at Secure Channel initiation and which is required for the whole Secure Channel Session. On successful initialization of the Secure Channel Session, the Current Security Level is set to the same value as the compulsory Session Security Level. The Current Security Level is updated (R-MAC or not) on the successful processing of the BEGIN R-MAC SESSION / END R-MAC SESSION commands.

Notes:

• Processing this method shall comply to the rules of the Secure Channel Protocol implemented by the Security Domain;
• The method is responsible for receiving the data field of commands that are recognized;
• The applet is responsible for recognizing commands that the method refused to process ('6E00' and '6D00');.
• The applet is responsible for outputting status bytes returned due to the processing of instructions recognized by the method;
• If response data is present, this data will be placed in the APDU buffer at offset ISO7816.OFFSET_CDATA. The return code indicates the length and the applet is responsible for outputting this data.

Parameters:

apdu - the incoming APDU object.

Returns:

the number of bytes to be output.

Throws:

javacard.framework.ISOException - with the following reason codes (other security mechanism related status words may be returned):

• ISO7816.SW_CLA_NOT_SUPPORTED class byte is not recognized by the method.
• ISO7816.SW_INS_NOT_SUPPORTED instruction byte is not recognized by the method.

wrap

short wrap(byte[] baBuffer,
           short sOffset,
           short sLength)
           throws java.lang.ArrayIndexOutOfBoundsException,
                  javacard.framework.ISOException

This method applies secure messaging to the current outgoing response according to the Current Security Level and Session Security Level of the Secure Channel Session.

Notes:

• Processing this method shall comply to the rules of the Secure Channel Protocol implemented by the Security Domain;
• This method attempts secure messaging processing of the current outgoing response when the Current Security Level indicates R_MAC and/or R_ENCRYPTION;
• If the Current Security Level does not indicate R_MAC and/or R_ENCRYPTION, when complying with the Secure Channel Protocol rules, this method will do no processing and the outgoing response message will remain as is in the APDU object. The returned length of the “wrapped” data is set to the value of the sLength parameter minus 2 (indicating the status bytes are no longer present at the end of the returned data);
• The applet is responsible for appending the expected status bytes at the end of the response data in order for them to be protected by secure messaging;
• The returned data does not include the status bytes;
• The method fails if the secure messaging of the incoming command is not successfully verified or does not match the Current Security Level (as defined either as the compulsory Session Security Level set at initialization of the Secure Channel Session or as the Current Security Level set by the setSecurityLevel() method). If the method fails, the Current Security Level is reset to NO_SECURITY_LEVEL, but not the compulsory Session Security Level;
• This method does not fail if a Secure Channel Session is not open (that is, when Session Security Level = NO_SECURITY_LEVEL) or if the corresponding session keys are not available.

Parameters:

baBuffer - the source of the data to be wrapped.

sOffset - the offset within baBuffer of the data to wrap.

sLength - the length of the data to wrap.

Notes:

• The length Li of the Response Data Field is automatically calculated by the Security Domain and prepended to the Response Data Field for computation of the R-MAC.

Returns:

the length of the wrapped data.

Throws:

javacard.framework.ISOException -

if security mechanism related status words might be returned.

java.lang.ArrayIndexOutOfBoundsException -

if wrapping produces data outside array bounds.

java.lang.SecurityException

- if baBuffer is not accessible in the caller’s context e.g. baBuffer is not a global array nor an array belonging to the caller context.

unwrap

short unwrap(byte[] baBuffer,
             short sOffset,
             short sLength)
             throws javacard.framework.ISOException

This method is used to process and verify the secure messaging of an incoming command according to the security level and Session Security Level of the current Secure Channel Session.

Notes:

• Processing this method shall comply to the rules of the Secure Channel Protocol implemented by the Security Domain;
• If NO_SECURITY_LEVEL, AUTHENTICATED or ANY_AUTHENTICATED only is indicated, when complying to the Secure Channel Protocol rules, this method will not attempt any secure messaging processing on the incoming command, the incoming command will remain as is within the incoming APDU object and the returned length of the “unwrapped” data is set to the value of the sLength parameter, otherwise a security error is returned;
• If the class byte does not indicate secure messaging (according to ISO/IEC 7816-4), this method will not attempt any secure messaging processing on the incoming command and the incoming command will remain as is within the incoming APDU object. When complying with the Secure Channel Protocol rules, the returned length of the “unwrapped” data is set to the value of the sLength parameter otherwise a security error is returned;
• The applet is responsible for receiving the data field of the command;
• Correct secure messaging processing of the unwrap() will result in the incoming command being reformatted within the incoming APDU object with all data relating to the secure messaging removed. A reformatted case 1 or case 2 command will include an Lc byte set to zero;
• If R_MAC is indicated in the Current Security Level of the Secure Channel Session, once secure messaging processing of the incoming command has successfully completed, R-MAC computation on the reformatted command (i.e. after all the data relating to secure messaging has been removed) will be initiated. If no secure messaging processing was required for the incoming command, R-MAC computation will be initiated on the unmodified incoming command, appended with a Lc byte of zero in event of a case 1 or case 2 command;
• Incorrect processing of the unwrap method will result in the information relating to the current Secure Channel being reset.
• This method does not fail if a Secure Channel Session is not open (that is, when Session Security Level = NO_SECURITY_LEVEL) or if the corresponding session keys are not available;
• The method fails if the secure messaging of the incoming command is not successfully verified or does not match the Current Security Level (as defined either as the compulsory Session Security Level set at initialization of the Secure Channel Session or as the Current Security Level set by the setSecurityLevel() method). If the method fails, the Current Security Level is reset to NO_SECURITY_LEVEL, but not the compulsory Session Security Level.

Parameters:

baBuffer - the source of the data to be unwrapped.

sOffset - the offset within baBuffer of the APDU data to unwrap, i.e. the offset of the command header.

sLength - the length of the APDU data to unwrap, i.e the length of the command header and data field.

Returns:

the length of the unwrapped data, i.e the length of the command header and data field.

Throws:

javacard.framework.ISOException - with the following reason code (other security mechanism related status words may be returned):

• ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED if secure messaging verification failed.
• ISO7816.SW_CLA_NOT_SUPPORTED class byte is not recognized by the method.

java.lang.SecurityException -

if baBuffer is not accessible in the caller’s context e.g. baBuffer is not a global array nor an array belonging to the caller context.

decryptData

short decryptData(byte[] baBuffer,
                  short sOffset,
                  short sLength)
                  throws javacard.framework.ISOException

This method is used to decrypt data located in the input buffer.

Notes:

• Processing this method shall comply to the rules of the Secure Channel Protocol implemented by the Security Domain;
• The Security Domain implicitly knows the key to be used for decryption.
• The Security Domain is implicitly aware of any padding that may be present in the decrypted data and this is discarded.
• The clear text data replaces the ciphered data within the byte array. The removal of padding may cause the length of the clear text data to be shorter than the length of the ciphered data.
• The applet is responsible for checking the integrity of the decrypted data.
• A Secure Channel Session shall be opened and a sensitive data decryption key shall be available;
• This method fails if a Secure Channel Session is not open (i.e. Session Security Level = NO_SECURITY_LEVEL) or if the corresponding session keys are not available.

Parameters:

baBuffer - the source byte array.

sOffset - offset within the source byte array to start the decryption.

sLength - the number of bytes to decrypt.

Returns:

The length of the clear text data.

Throws:

javacard.framework.ISOException - with the following reason codes:

ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED if a Secure Channel Session has not been opened.

ISO7816.SW_WRONG_LENGTH if the length of data to be decrypted is not valid.

java.lang.SecurityException -

if baBuffer is not accessible in the caller’s context e.g. baBuffer is not a global array nor an array belonging to the caller context.

encryptData

short encryptData(byte[] baBuffer,
                  short sOffset,
                  short sLength)
                  throws java.lang.ArrayIndexOutOfBoundsException

This method is used to encrypt data located in the input buffer.

Notes:

• Processing this method shall comply to the rules of the Secure Channel Protocol implemented by the Security Domain;
• The Security Domain is implicitly aware of any padding that must be applied to the clear text data prior to encryption according to the Secure Channel Protocol;
• The Security Domain implicitly knows the key to be used for encryption.
• The ciphered data replaces the clear text data within the byte array.
• A Secure Channel Session shall be opened and a sensitive data encryption key shall be available;
• This method fails if a Secure Channel Session is not open (i.e. Session Security Level = NO_SECURITY_LEVEL) or if the corresponding session keys are not available.

Parameters:

baBuffer - the byte array containing the data to be processed.

sOffset - offset within the byte array to start the encryption.

sLength - the number of bytes to encrypt.

Returns:

The length of the encrypted data.

Throws:

java.lang.ArrayIndexOutOfBoundsException -

if enciphering produces data outside array bounds.

javacard.framework.ISOException - with the following reason code:

ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED if a Secure Channel Session is not open.

java.lang.SecurityException

- if baBuffer is not accessible in the caller’s context e.g. baBuffer is not a global array nor an array belonging to the caller context.

resetSecurity

void resetSecurity()

This method is used to reset all information relating to the current Secure Channel Session. It resets both the compulsory Session Security Level and the Current Security Level to NO_SECURITY_LEVEL, terminates the current Secure Channel Session and erases all session keys.

Notes:

• It is strongly recommended that applets using the services of a Security Domain invoke this method in the Applet.deselect() method;
• The Security Domain will reset all information relating to the current Secure Channel, i.e. all Secure Channel session keys, state information and security level information will be erased.
• This method shall not fail if no Secure Channel has been initiated.

getSecurityLevel

byte getSecurityLevel()

This method returns, from the requester's standpoint, the Current Security Level coded as a bit-map according to Table 10 1 indicating whether entity authentication has occurred and what level of security is currently applicable to command and response messages processed by the unwrap() and wrap() methods.

Notes:

• Applets must invoke this method to ensure that application specific security requirements have been previously met or will be enforced by the Security Domain.
• More than one level of security may be active and these may change during a Secure Channel, e.g. an R_MAC session may be initiated during a C_MAC session.
• The Current Security Level may be different at the same time for an Application invoking the method and its associated Security Domain depending on the Secure Channel Protocol and the authenticated off-card entity's Application Provider ID (e.g. it may be ANY_AUTHENTICATED for the application and AUTHENTICATED for its associated Security Domain).

Returns:

The current Security Level